Tech Arsenal 1/Tech Arsenal (Arsenal Computer).ISO/tek-04/super30a.zip/SMUTIL.ZIP/TEMPLATE.WS

WordStar Document | 1992-02-08 | 17KB | 443 lines

=========================[ Work Sheet Template ]============================

                           General Instructions

To use this file, first make a copy called TEMPLATE.SM.  Then edit the
COPY only.

This is a blank template that goes with your Template Worksheet.  To
use it follow along on your worksheet while filling in each choice in
this file.  Many examples are shown here :  make sure you delete the ones
that don't apply to your language products.  For other template examples,
see the sample configurations contained in the sample archives (MS.EXE,
BORT.EXE etc.).

All Script Command Statements start with an asterisk (*) on the first
character of a line (there must be no spaces), followed by the command
and its arguments.

All values are contained within |vertical lines|.

IMPORTANT:  Even if you are using a pre-defined template that came with
SUPER-MAINT you MUST set the correct arguments in the *INCLUDE and *LIBRARY
statements.

You will notice a few keywords used in this file.  The most important one is
"NAME."  If SUPER-MAINT sees this in the second field of many statements it
replaces the keyword with the actual name of a file.  So |NAME|.OBJ| might
be translated to MYFILE.OBJ when the response file is written.  You may
also use explicit names:  |MYFILE|.EXE| will ALWAYS be written as MYFILE.EXE.

There are four groups of instructions to fill in:

                     1.  General Command Statements
                     2.  Linker Command Group
                     3.  Librarian Command Group
                     4.  Compiler Command Group

General commands contain a miscellaneous collection of information SUPER-
MAINT needs to work correctly with your compiler and other language
products.

Command groups are mainly used to define how a response file is written.
Each command represents a line or group of lines in your response file.
For example, the *C command defines a how a list of files is written: in
a linker response file they would be the names of the object files being
linked.  "Before" and "After" action blocks can also be defined in a
command group.  These are commands that must take place just before or
just after the link (or librarian) command.

This file is heavily commented and has alternative versions of some of
the command statements.  You should make a copy of this file (call it
TEMPLATE.SM), make sure you only have the command statements for YOUR
compiler(s), assembler, linker and/or librarian, deleting the alternative.

For example, *AC1 |MAC|NAME and *AC1 |NAME|MAC are both listed.  Delete
the one that doesn't apply to your compiler.

When you are satisfied that your Template file works correctly you should
DELETE ALL THE COMMENTS so that SUPER-MAINT will run faster.  (You may leave
comments in the file if you choose to).

======================================================================== ====

===================[ Section 1: General Command Statements ]================

You need to have one of each of the commands listed in the General Command
Group below.  The only exceptions are: You may replace the six *ACn
statements with a single *AC statement if the order of macros and file names
(and/or response files) is always the same.  If you are not moving any
macros to the end of the command line, or are moving one or more for ALL
your languages, linker and librarian you may replace the five *MACROn
statements with one *MACRO statement.

Just edit the commands in this group, deleting examples you don't need.
------------------------------------------------------------------------ ----

A 20 Character Description of Your Setup
*B  |EmmaSoft Compilers|
------------------------------------------------------------------------ ----
Now we set the *AC commands.  These tell SUPER-MAINT  what order your
compiler and other language tools take their commands in.

The order of the command for language 1:

This choice puts flags before the name of the program being compiled
(most compilers work this way), for example:  CC -AS -AB PROGNAME.C

*AC1 |MAC|NAME

This one, on the other hand, puts the flags AFTER the name (Clipper works
this way), for example:  CC PROGNAME.C -AS -AB

*AC1 |NAME|MAC
------------------------------------------------------------------------ ----
Do the same for languages 2 and/or 3 (even if you aren't using them):

*AC2 |MAC|NAME
*AC3 |MAC|NAME
------------------------------------------------------------------------ ----
Now do the same for your Linker.  This calls the response file after the
command flags have been called.  Example:  LINKER /E /ST:20000 @RESFILE.RES

*AC4 |MAC|RES|
------------------------------------------------------------------------ ----
Some librarians want the library name in the response file, so all you
need to do to call it is:  LIB /F1 /F2 @ RESFILE.RES

*AC5 |MAC|RES|

Others want you to put the library name on the command line like this:
LIB /F1 /F2 MYLIBL.LIB @RESFILE.RES

*AC5 |MAC|NAME|RES|

------------------------------------------------------------------------ ----
This last one is for "Before" or "After" action block languages.  The
Windows SDK resource compiler is an example.  If you are not using
"Before" or "After" action blocks just leave this as is.

*AC6 |MAC|NAME
------------------------------------------------------------------------ ----
If all your language tools use the following format you can replace all
the *ACn commands with one command.  You must either use ALL SIX *ACn
commands, OR this one single command.  Do not use both!

*AC  |MAC|NAME|

The above is the equivalent of *AC1, 2, 3, and 6 with arguments: |MAC|NAME
and *AC4 and 5 with arguments: |MAC|RES|.


------------------------------------------------------------------------ ----
Normally you want to keep all your macros together.  If so you only need
one Macro order statement.

*MACRO ||

In RARE cases you may want some of your macros to appear LAST on the
command line.  If so you'll need a set of 5 Macro Statements:

*MACRO1 ||
*MACRO2 |8|
*MACRO3 ||
*MACRO4 ||
*MACRO5 ||

In the above example language number 2 (which may be a compiler or an
assembler) puts all it's macros together except for the Flags2 Macro,
which appears at the end.  So a command in the make file for language
one would come out: CC -AS -Od -W4 MYFILE.C, and the same command for
language 2 would come out: CC -AS -Od MYFILE.C -W4  (assuming that the
flag -W4 is in the L2F2 - Language 2, Flags 2 - macro).

You can use numbers from 1 to eight.  See the manual for more
explanation.
------------------------------------------------------------------------ ----
Below is the default symbol used to tell your linker or librarian that
the following text is a response file.  (Example: LINK @RESFILE.RES).
If your linker or librarian uses a different symbol replace the "@"
sign with it.  (NOTE:  In the make file you will always see a "@" sign.
This is the symbol SM needs to know it is passing a response file.
However when it sends the command to your linker or librarian it will
replace the "@" in the make file with the symbol defined here.  (NOTE:
Most users will NOT have to change this).

*RC |@|
------------------------------------------------------------------------ ----
This tells SUPER-MAINT what the extension of your library files is.
(EXAMPLE:  MYLIB.LIB)  Do not include the dot.

*FXL |LIB|
------------------------------------------------------------------------ ----
This tells SUPER-MAINT what the extension of your object files is.
(EXAMPLE:  MYPROG.OBJ)  Do not include the dot.

*FXO |OBJ|
------------------------------------------------------------------------ ----
====IT IS VERY IMPORTANT that you correctly set the next two statements.====
====Each defines a global library for SM to search for header files and ====
====libraries when they are used as dependents in a make file.          ====
------------------------------------------------------------------------ ----
This statement tells SUPER-MAINT where your header files are kept:

*INCLUDE |D:\C\INCLUDE|
------------------------------------------------------------------------ ----
This statement tells SUPER-MAINT where your libraries are kept.

*LIBRARY |D:\C\LIB|
------------------------------------------------------------------------ ----

===================[ Section 2: Linker Command Statements ]=================

Command groups always start with an "ON" statement and end with an "OFF"
statement.  This section defines how response files are written for your
linker.  Put the commands in the order they would appear in a response file.
The order of the commands sandwiched between *LINKON and *LINKOFF is
determined by the order your linker requires them in.  See the manual for
your linker for more information.

*LINKON
------------------------------------------------------------------------ ----
In linker command groups the *C command tells how to list the object files.
There are up to five arguments as follows:

            Symbol Before File Name
            Name
            Extension
            Sym After Name
            Use "After" Symbol each time or all but the last time?

Here are some examples:

If your object file list looks like this:

        MYFILE1+
        MYFILE2+
        MYFILE3
Use this command (notice that the ALLBUT key word places the '+' after
all but the last object file name).

*C  ||NAME||+|ALLBUT|

Here are some more examples:

        OB MYFILE1
        OB MYFILE2
        OB MYFILE3

*C  |OB|NAME||||

Note in this example that you DO put the dot in the file extension:

         MYFILE1.OBJ&
         MYFILE2.OBJ&
         MYFILE3.OBJ

*C  ||NAME|.OBJ|&|ALLBUT|
------------------------------------------------------------------------ ----
This tells the name of the executable file:

         MYPROG

*E  ||NAME

         MYPROG.EXE

*E  ||NAME|.EXE

------------------------------------------------------------------------ ----
This tells the name of the map file:
         MYPROG

*M  ||NAME

         MYPROG.MAP

*M  ||NAME|.MAP

If you sometimes do NOT list a map file name you must ALSO tell SUPER-MAINT
how to do that:

*MN |nul|

or

*MN |;|
------------------------------------------------------------------------ ----
This command tells how to list libraries;

        MYLIB1+
        MYLIB2+
        MYLIB3
Use this command (notice that the ALLBUT key word places the '+' after
all but the last object file name).

*L  ||NAME||+|ALLBUT|

Here are some more examples:

        LIB MYLIB1
        LIB MYLIB2
        LIB MYLIB3

*C  |LIB|NAME||||

Note in this example that you DO put the dot in the file extension:

         MYLIB1.LIB&
         MYLIB2.LIB&
         MYLIB3.LIB

*L  ||NAME|.LIB|&|ALLBUT|

If you sometimes link without using any libraries you need a compainion
command here.  Just type in the text needed when there are no libraries:

*LN |;|
------------------------------------------------------------------------ ----
This command tells how to list the Definitions File:

This example shows a way of not using a definitions file:

*D |nul.def|

Here's a way to use one:

*D ||NAME|.DEF|

------------------------------------------------------------------------ ----
If you are using "Before" or "After" command blocks (such as the Resource
Compiler for Microsoft's SDK for Windows) they should go at the end of this
command group, just before the *LINKOFF statement.

------------------------------------------------------------------------ ----
This statement turns off (ends) this command group.

*LINKOFF
------------------------------------------------------------------------ ----
=================[ Section 3: Librarian Command Statements ]================

Command groups always start with an "ON" statement and end with an "OFF"
statement.  This section defines how response files are written for your
librarian.  Put the commands in the order they would appear in a response
file.

Librarians sometimes question you in a different order when the library
already exists than they do when the library being created is new.  For
this reason you may have to use "companion" commands in your library
response file (Microsoft and Borland librarians require this).

*LIBON
------------------------------------------------------------------------ ----
This command tells the name of the library.  (If your *AC command has the
library name in it you should not repeat it in the response file)

         MYLIB3.LIB

*E  ||NAME|.LIB|

         MYLIB3

*E  ||NAME|
------------------------------------------------------------------------ ----
The Microsoft librarian asks if it is a new library when the library does
not already exist.  So for NEW LIBRARIES ONLY you have to answer "Y" for
"yes."  The *TY command only works when a library is new.

*TY  |Y|

You could also use the *T command with the NEWNLY keyword.  This keyword
tells SUPER-MAINT only to use this command if a library is new.

*T  |Y||||NEWNLY
------------------------------------------------------------------------ ----
Now here is an example of companion commands.  If a library is new you
just add the object files to it.  When it already exists you have to delete
the old version of an object file before adding the new version.  There are
four keywords you can use in the fifth (last) slot to control this.  For new
libraries that have a symbol after the name of all but the last object file
you use ALLBUTN.  If there is no last symbol (or it comes after every object
file name) you use NEWNLY.  In like fashion you use ALLBUTO and OLDNLY for
old libraries (those that already exist).

Examples:    New                      Old

             MYFILE1.OBJ&             -+ MYFILE1.OBJ&
             MYFILE2.OBJ&             -+ MYFILE2.OBJ&
             MYFILE3.OBJ              -+ MYFILE3.OBJ&

*C  ||NAME|.OBJ|&|ALLBUTN|
*C  |-+ |NAME|.OBJ|&|ALLBUTO|

Examples:    New                      Old

             ADD MYFILE1.OBJ             DEL MYFILE1.OBJ
             ADD MYFILE2.OBJ             ADD MYFILE1.OBJ
             ADD MYFILE3.OBJ             DEL MYFILE2.OBJ
                                         ADD MYFILE2.OBJ
                                         DEL MYFILE3.OBJ
                                         ADD MYFILE3.OBJ

*C  |ADD|NAME|.OBJ||NEWNLY|
*C  |DEL |NAME|.OBJ||OLDNLY|
*C  |ADD |NAME|.OBJ||OLDNLY|

------------------------------------------------------------------------ ----
Here's another text command.  This will be used with new libraries only:

*T  |nul|
------------------------------------------------------------------------ ----
Here's a command that is only used in existing libraries.  (It is the
equivalent of *T  |;||||OLDNLY

*LX |;|
------------------------------------------------------------------------ ----
If you are using "Before" or "After" command blocks they should go at the
end of this command group, just before the *LIBOFF statement.

------------------------------------------------------------------------ ----
This statement turns off (ends) this command group.

*LIBOFF
------------------------------------------------------------------------ ----

==========[ Section 4: Compiler Response File Command Statements ]==========

Compiler response files can greatly speed up your program building because
the compiler is only called one time.  If your compiler supports the use of
response files you may want to use this feature.  However, this only works
with SUPER-MAINT if you are passing exactly the same flags to the compiler
for every file it builds.  SUPER-MAINT reads the command line from the first
appropriate action block and uses it for all the files being built in that
pass.

Command groups always start with an "ON" statement and end with an "OFF"
statement.  This section defines how response files are written for your
compile.

*COMPON
------------------------------------------------------------------------ ----
If your compiler supports the use of response files use the foillowing command
statement (all the compilers that we are aware of that can use response files
use this format with just one source file name on each line of the response
file.  Example:

                     FILE1.C
                     FILE2.C
                     FILE3.C

*CRFC ||NAME||||

------------------------------------------------------------------------ ----
Even if your compiler doesn't use response files it may be capable of
accepting more than one source file on a command line.  If so, use the
COMPLINE key word in your *CRFC statement.
(Example:  CC -AS -Od FILE1.C  FILE2.C  FILE3.C)

*CRFC |COMPLINE|
------------------------------------------------------------------------ ----
This statement turns off (ends) this command group.
*COMPOFF
=================[ End Of Worksheet Template Example File ]=================